Collections

Collections (also known as “shopping carts”) are a common feature of many web sites, and allow users to keep track of a particular set of items. This is particularly useful in the context of an image database, in which a user may want to gather a set of images from a number of different searches.

PortWeb has built-in support for collections. PortWeb creates a shopping cart for any user who wants to track items (assuming the page is designed to make use of shopping carts). PortWeb can maintain a user’s shopping cart across multiple sessions, and can maintain separate carts for each catalog a user visits.

Collection record sets are stored in a proprietary database file named “PortWeb.wdb”. The Administrator has the ability to set how long collections are kept in the database. Below are the various commands. Note that the collection requests only work correctly for users who allow their browsers to accept cookies.

Note: Collections are stored separately for different catalogs. In other words, items from one catalog cannot be added to the same shopping cart as items from a different catalog.

Working with Collections

The common user experience with a collection in PortWeb is:

The user submits a search via the query command.
The user is returned a web page generated by the query request.
On the page is a button reading “Add to my shopping cart.”
Clicking this generates a Collection request to add one or more records. If no collection currently exists for the current user in the current catalog (based on the cookie received in the query), a new collection record is created.
The result of the Add command is a newly generated page showing the current collection, and a cookie is placed on the user’s system.
From this shopping cart page, the user can choose to remove items from the cart.

To add collection functionality to a site powered by PortWeb, you can either use collection macros, or use the collection commands directly. Normally it is easier to use the macros, as PortWeb will generate much of the necessary HTML automatically. However, there may be times when the flexibility provided by using the collection commands is desired.

Collection Templates

Collection templates are not really any different than any other response template. The primary difference is that they are displaying results from a user’s collection set, instead of results from a particular query. Often the same response templates can be used for both a query and a collection. Of course, if you want to provide the users the ability to manipulate the collection, you’ll need to create collection templates that make use of the Add and Remove commands.

For more information on collection-specific macros, see PortWeb Templates.

Collections Tutorial

To see how collections work, you can look at the PortWeb Basic Tutorial then examine the Collection macro examples.

Collection Commands

Add Command

The add command adds one or more records to the user’s collection set. If no collection set for the user of the particular catalog exists, then a new collection set is created and a cookie is returned to the user. The parameters specified are:

Add Command

Parameter

Description

catalog

Specifies the alias of the catalog is to be used. The alias is mapped via the settings file to either a catalog on disk or a catalog being served by a Portfolio server.

rid

Specifies the record ID in the catalog. Record IDs are unique within a catalog. This can be one record or a list of records (e.g., &ldots;&rid=70&rid=75&rid=85&&ldots;). Any invalid RIDs are ignored.

template [OPTIONAL]

Specifies the alias of the template to be used. If this parameter is not passed in, a default Export HTML template is used (a basic thumbnail view layout).

sorton [OPTIONAL]

Identifies an indexed, single-valued field on which the found set should be sorted. If it is not specified, the order of the record set is the order returned by the Find.

ascending [OPTIONAL]

Specifies the order in which the record set is sorted. A value of 0 indicates ascending, a value of 1 indicates descending. If the sorton parameter is not provided, this parameter is ignored. If the sorton parameter is provided and this parameter is not, the default sort order is 0 (ascending).

offset [OPTIONAL]

A positive integer indicating how many records have already been displayed from the collection. If the parameter is not specified, the display should start from the first record in the collection.

Remove Command

The remove command removes one or more records from the user’s collection set. If no cookie exists, or if the ID in the user’s cookie does not match any records in the collections database, or if the IDs in the cookie do not match the catalog specified in the request, then an error is returned to the user on the “No matching records found” page.

The parameters specified are:

Remove Command

Parameter

Description

catalog

Specifies the alias of the catalog is to be used. The alias is mapped via the settings file to either a catalog on disk or a catalog being served by a Portfolio server.

rid

Specifies the record ID in the catalog. Record IDs are unique within a catalog. This can be one record or a list of records (e.g., &ldots;&rid=70&rid=75&rid=85&&ldots;). Any invalid RIDs are ignored.

template [OPTIONAL]

Specifies the alias of the template to be used. If this parameter is not passed in, a default Export HTML template is used (a basic thumbnail view layout).

sorton [OPTIONAL]

Identifies an indexed, single-valued field on which the found set should be sorted. If it is not specified, the order of the record set is the order returned by the Find.

ascending [OPTIONAL]

Specifies the order in which the record set is sorted. A value of 0 indicates ascending, a value of 1 indicates descending. If the sorton parameter is not provided, this parameter is ignored. If the sorton parameter is provided and this parameter is not, the default sort order is 0 (ascending).

offset [OPTIONAL]

A positive integer indicating how many records have already been displayed from the collection. If the parameter is not specified, the display should start from the first record in the collection.

Show Command

The show command displays the records in a user’s collection set.

The parameters are:

Show Command

Parameter

Description

catalog

Specifies the alias of the catalog is to be used. The alias is mapped via the settings file to either a catalog on disk or a catalog being served by a Portfolio server.

rid

Specifies the record ID in the catalog. Record IDs are unique within a catalog. This can be one record or a list of records (e.g., &ldots;&rid=70&rid=75&rid=85&&ldots;). Any invalid RIDs are ignored.

template [OPTIONAL]

Specifies the alias of the template to be used. If this parameter is not passed in, a default Export HTML template is used (a basic thumbnail view layout).

sorton [OPTIONAL]

Identifies an indexed, single-valued field on which the found set should be sorted. If it is not specified, the order of the record set is the order returned by the Find.

ascending [OPTIONAL]

Specifies the order in which the record set is sorted. A value of 0 indicates ascending, a value of 1 indicates descending. If the sorton parameter is not provided, this parameter is ignored. If the sorton parameter is provided and this parameter is not, the default sort order is 0 (ascending).

offset [OPTIONAL]

A positive integer indicating how many records have already been displayed from the collection. If the parameter is not specified, the display should start from the first record in the collection.

Cookies

Whenever a collection request (add, show, remove) is successful, a cookie containing the collection’s id number is sent from the web server to the client’s browser. If the cookie is accepted, it is stored on the user’s machine, and sent back to PortWeb for every subsequent request.

Users can refuse individual cookies, or set their browsers to refuse all cookies. If cookies are refused, every add request will create a new, one-item collection in PortWeb’s collection database. In this case, the results of all collection requests (add, show, remove) will act as if the request had been applied to an empty cart.

Cookies set by PortWeb have an expiration date that matches the plug-in’s collection expiration setting.

Add Command
Parameter	Description
catalog	Specifies the alias of the catalog is to be used. The alias is mapped via the settings file to either a catalog on disk or a catalog being served by a Portfolio server.
rid	Specifies the record ID in the catalog. Record IDs are unique within a catalog. This can be one record or a list of records (e.g., &ldots;&rid=70&rid=75&rid=85&&ldots;). Any invalid RIDs are ignored.
template [OPTIONAL]	Specifies the alias of the template to be used. If this parameter is not passed in, a default Export HTML template is used (a basic thumbnail view layout).
sorton [OPTIONAL]	Identifies an indexed, single-valued field on which the found set should be sorted. If it is not specified, the order of the record set is the order returned by the Find.
ascending [OPTIONAL]	Specifies the order in which the record set is sorted. A value of 0 indicates ascending, a value of 1 indicates descending. If the sorton parameter is not provided, this parameter is ignored. If the sorton parameter is provided and this parameter is not, the default sort order is 0 (ascending).
offset [OPTIONAL]	A positive integer indicating how many records have already been displayed from the collection. If the parameter is not specified, the display should start from the first record in the collection.